<?php
/**
 * Copyright (c) 2008, Till Klampaeckel
 * 
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * 
 *  * Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright notice, this
 *    list of conditions and the following disclaimer in the documentation and/or
 *    other materials provided with the distribution.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * PHP Version 5
 *
 * @category Services
 * @package  Services_Plazes
 * @author   Till Klampaeckel <till@php.net>
 * @license  http://www.opensource.org/licenses/bsd-license.php The BSD License
 * @version  CVS: $Id$
 * @link     http://code.google.com/p/servicesplazes/
 */

/**
 * Services_Plazes_Adapter_Sessions_Exception
 */
require_once 'Services/Plazes/Adapter/Sessions/Exception.php';

/**
 * A class to interface the API of plazes.com.
 *
 * @category Services
 * @package  Services_Plazes
 * @author   Till Klampaeckel <till@php.net>
 * @license  http://www.opensource.org/licenses/bsd-license.php The BSD License
 * @version  Release: @package_version@
 * @link     http://code.google.com/p/servicesplazes/
 */
final class Services_Plazes_Adapter_Sessions extends Services_Plazes
{
    /**
     * @var $httpRequest
     */
    protected $httpRequest;
    
    /**
     * @var $endpoint
     */
    protected $endpoint;

    /**
     * __construct
     */
    private function __construct()
    {
    }
    
    /**
     * factory
     *
     * Used to initialize Sessions adapter.
     *
     * @param array $params Params passed in from Services_Plazes.
     *
     * @return Services_Plazes_Adapter_Sessions
     * @uses Services_Plazes::setParams()
     */
    static function factory($params)
    {
        $sessions = new Services_Plazes_Adapter_Sessions;
        $sessions->setParams($params);
        
        return $sessions;
    }
    
    /**
     * getSession
     *
     * @return string
     * @throws Services_Plazes_Adapter_Sessions_Exception In case the request fails.
     */
    public function getSession()
    {   
        $url = $this->endpoint . '/sessions.xml';
        try {
            $response = $this->makeRequest($url, 'POST', '');
        } catch (Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Sessions_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        return $this->_parseResponse($response);
    }

    /**
     * getLoginUrl
     *
     * Supply a plazes.com-URL and return a login including the session ID to the 
     * user which can be used to authenticate and login. This URL is for the user to
     * 'click' on - beyond an API request.
     *
     * This method doesn't validate if the supplied URL exists - make sure to check
     * that yourself.
     *
     * @param string $url A URL, e.g.: http://plazes.com/messages
     *
     * @return string
     * @uses   self::getSession()
     * @todo   Verify what we got from parse_url().
     */
    public function getLoginUrl($url)
    {
        $parts      = parse_url($url);
        $session_id = $this->getSession();

        return $parts['scheme'] . '://' . $parts['host'] . '/sessions/' . $session_id . $parts['path'];
    }
    
    /**
     * _parseResponse
     *
     * @param string $response The response received from the API.
     *
     * @return array
     */
    private function _parseResponse($response)
    {
        $simpleXml = simplexml_load_string($response);
        return (string) $simpleXml->id;
    }
}
?>
